Typical HAL RNG use cases for migration

This section provides information about the applicable HAL RNG architecture use cases.

Note

The random number generation functions, HAL_RNG_GenerateRandomNumber and HAL_RNG_GenerateRandomNumber_IT, take a buffer and its size as input and fill it with the N requested random number. The user no longer needs to implement a loop to retrieve random numbers one by one.

Use case: RNG generate NIST compliant random numbers in polling mode

Sequence diagram

RNG generate NIST compliant random numbers in polling mode

@startuml participant "Application" as App participant "RNG" as RNG App -> RNG: HAL_RNG_Init() App -> RNG: HAL_RNGEx_SetConfig() App -> RNG: HAL_RNG_GenerateRandomNumber() App -> RNG: HAL_RNGEx_RecoverSeedError() @enduml

Code snippet

HAL1

HAL2 

#define LENGTH 8
uint32_t aRandom32bit[LENGTH];
RNG_HandleTypeDef hrng;
RNG_ConfigTypeDef p_config;

hrng.Instance = RNG;
hrng.Init.ClockErrorDetection = RNG_CED_ENABLE;

p_config.Config1 = 0x01;
p_config.Config2 = 0x00;
p_config.Config3 = 0x02;
p_config.ClockDivider = RNG_CLKDIV_BY_32;
p_config.NistCompliance = RNG_NIST_COMPLIANT;
P_config.AutoReset = RNG_ARDIS_ENABLE;
p_config.HealthTest = 0x00009AAE;
p_config.NoiseSource = 0x000358D1;

HAL_RNG_Init(&hrng);
HAL_RNGEx_SetConfig(&hrng, &p_config);

for (int cnt=0; cnt < LENGTH - 1; cnt++)
{
   if (HAL_RNG_GenerateRandomNumber(&hrng,
                 &aRandom32bit[cnt]) == HAL_ERROR)
   {

       HAL_RNGEx_RecoverSeedError(&hrng);
   }
}

#define LENGTH 8
uint32_t aRandom32bit[LENGTH];
hal_rng_handle_t hrng;


HAL_RNG_Init(&hrng, HAL_RNG);

HAL_RNG_SetCertifiedNISTConfig(&hrng);

HAL_RNG_EnableClockErrorDetection(&hrng);

if (HAL_RNG_GenerateRandomNumber(&hrng,
                             aRandom32bit, LENGTH) == HAL_ERROR)
   {

       HAL_RNG_RecoverSeedError(&hrng);
   }

Key changes

  1. In HAL2, random number generation APIs take a buffer and its size and fill it in one call.

  2. Configuration and recovery APIs are updated (for example, HAL_RNG_SetCertifiedNISTConfig and HAL_RNG_RecoverSeedError).

Use case: RNG generate NIST compliant random numbers in interrupt mode

Sequence diagram

RNG generate NIST compliant random numbers in interrupt mode

@startuml participant "Application" as App participant "RNG" as RNG participant "IRQ Handler" as isr App -> RNG: HAL_RNG_Init() App -> RNG: HAL_RNGEx_SetConfig() App -> RNG: HAL_RNG_GenerateRandomNumber_IT() App -> RNG: HAL_RNGEx_RecoverSeedError() isr <- : Interrupt isr -> RNG: HAL_RNG_IRQHandler() RNG -> App: HAL_RNG_ReadyDataCallback() @enduml

Code snippet

HAL1

HAL2 

#define LENGTH 8
RNG_HandleTypeDef hrng;
uint32_t aRandom32bit[LENGTH];
RNG_ConfigTypeDef p_config;

hrng.Instance = RNG;
hrng.Init.ClockErrorDetection = RNG_CED_ENABLE;

p_config.Config1 = 0x01;
p_config.Config2 = 0x00;
p_config.Config3 = 0x02;
p_config.ClockDivider = RNG_CLKDIV_BY_32;
p_config.NistCompliance = RNG_NIST_COMPLIANT;
P_config.AutoReset = RNG_ARDIS_ENABLE;
p_config.HealthTest = 0x00009AAE;
p_config.NoiseSource = 0x000358D1;

HAL_RNG_Init(&hrng);
HAL_RNGEx_SetConfig(&hrng, &p_config);
for (int cnt=0; cnt < LENGTH - 1; cnt++)
{
   if (HAL_RNG_GenerateRandomNumber_IT(&hrng) == HAL_ERROR)
   {

       HAL_RNGEx_RecoverSeedError(&hrng);
   }
}

#define LENGTH 8
hal_rng_handle_t hrng;
uint32_t aRandom32bit[LENGTH];

HAL_RNG_Init(&hrng, HAL_RNG);

HAL_RNG_SetCertifiedNISTConfig(&hrng);

HAL_RNG_EnableClockErrorDetection(&hrng);

if (HAL_RNG_GenerateRandomNumber_IT(&hrng,
                                aRandom32bit, LENGTH) == HAL_ERROR)
   {

       HAL_RNG_RecoverSeedError(&hrng);
   }

Key changes

  1. HAL2 interrupt-based generation reports completion through HAL_RNG_GenerationCpltCallback.

  2. In HAL2, random number generation APIs take a buffer and its size and fill it in one call.

Related examples in HAL2

Example name

Brief

candidate_nist_config_it

How to use the HAL API to generate random numbers with the RNG peripheral, in interrupt mode and with HAL register callbacks.